<?php
/**
 * php GEM Project
 * 
 * LICENSE
 * 
 * PHP System Architecture Enabling Rapid Application Deployment and Scalability
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 * 
 * @copyright Copyright (C) 2010 Zeletron LLC (http://zeletron.com)
 * @license http://gem.zeletron.com/license
 */

/*
 * GEM/Service/Response.php
 * 
 *
 * 
 * @author David Joly
 * @link http://zeletron.com
 * 
 * @category GEM
 * @package GEM_Service
 */
class GEM_Service_Response
{
	/** Service Response Codes */
	const RESPONSE_CODE_SUCCESS = 100;
	const RESPONSE_CODE_ERROR = 200;
	const RESPONSE_CODE_INVALID = 300;
	const RESPONSE_CODE_DENIED = 400;
	
	/**
	 * Has the response persisted?
	 * 
	 * @var boolean
	 */
	protected $_persisted = false;
	
	/**
	 * Service Response Status Code
	 * 
	 * @var int
	 */
	protected $_status;
	
	/**
	 * Service Response Message
	 * 
	 * @var string
	 */
	protected $_message;
	
	/**
	 * Service Response Form
	 * 
	 * @var Zend_Form
	 */
	protected $_form;
	
	/**
	 * Should the form persist?
	 * 
	 * @var boolean
	 */
	protected $_formPersist;
	
	/**
	 * Service Response Constructor
	 * WARNING:
	 *  Zend_Form objects passed to the response object will automatically be persisted with
	 *  the response object for a full request cycle. Some forms CANNOT be persisted. If you are 
	 *  receiving fatal exceptions at the end the request, the exception is occurring during 
	 *  serialization. Setting the $formPersist parameter to FALSE will solve the exception problem 
	 *  if the form object is the culprit.
	 *  
	 *  For example, {@see GEM_Form_UserSignupForm} makes use of timezone_identifiers_list() that caused 
	 *  exceptions upon serialization. If you want to use functions and objects that can't serialize, 
	 *  you will need to set $formPersist to FALSE. This was done in the method {@see GEM_Service_User#signup()}
	 *  to prevent the form from attempting to persist yet still provide client code with the form object.
	 *    
	 * 
	 * @param int $status The Response status code
	 * @param string $message | optional The message issued by the service action method
	 * @param Zend_Form $form | optional A form object used by the action method
	 * @param boolean $formPersist |optional, defaults to true. 
	 * @return void
	 * @throws GEM_Service_Exception
	 */
	public function __construct($status,$message = null,$form = null, $formPersist = true)
	{
		if(!is_int($status) 
			|| (!is_null($message) && !is_string($message)) 
			|| (!is_null($form) && !$form instanceof Zend_Form)
		) throw new GEM_Service_Exception("Invalid parameter(s) detected.");
		$this->_status = $status;
		$this->_message = $message;
		$this->_form = $form;
		$this->_formPersist = $formPersist;
	}
	
	/**
	 * @return int
	 */
	public function getStatus()
	{
		return $this->_status;
	}
	
	/**
	 * @return string
	 */
	public function getMessage()
	{
		return $this->_message;
	}
	
	/**
	 * @return Zend_Form
	 */
	public function getForm()
	{
		return $this->_form;
	}
	
	/**
	 * If the input to the service was valid and no errors were encountered.
	 * 
	 * @return boolean
	 */
	public function isValid()
	{
		return $this->_status === self::RESPONSE_CODE_SUCCESS ? true : false;
	}
	
	/**
	 * If the service encountered an error.
	 * 
	 * @return boolean
	 */
	public function isError()
	{
		return $this->_status === self::RESPONSE_CODE_ERROR ? true : false;
	}
	
	/**
	 * If the service action was denied.
	 * 
	 * @return boolean
	 */
	public function isDenied()
	{
		return $this->_status === self::RESPONSE_CODE_DENIED ? true : false;
	}
	
	/**
	 * @return boolean
	 */
	public function getPersisted()
	{
		return $this->_persisted;
	}
	
	/**
	 * @param boolean $persisted
	 * @return void
	 * @throws GEM_Service_Exception
	 */
	public function setPersisted($persisted)
	{
		if(!is_bool($persisted))
			throw new GEM_Service_Exception(__METHOD__ . " expects a boolean parameter value.");
		$this->_persisted = $persisted;
	}
	
	/**
	 * Prevents form object from persisting
	 * 
	 * @return void
	 */
	public function __sleep()
	{
		if($this->_formPersist === false) $this->_form = null;
		return array_keys(get_object_vars($this));
	}
}